<!doctype html public "-//W3C//DTD HTML 4.01 Transitional//EN">
<html>
<head>
<meta name="robot" content="index,follow">
<title>Module car - Cell array module - Forth Foundation Library</title>
</head>
<body>
<h2>car - Cell array module</h2>
<h3>Module Description</h3>
<p>The car module implements a dynamic cell array.
</p>
<h3>Module Words</h3>
<dl>
</dl>
<h4>Cell Array Structure</h4>
<dl>
<dt><a name="word1"><b>car%</b>	( -- n )</dt>
<dd>Get the required space for a car variable</dd>
</dl>
<h4>Array creation, initialisation and destruction</h4>
<dl>
<dt><a name="word2"><b>car-init</b>	( +n car -- )</dt>
<dd>Initialise the array with an initial length n</dd>
<dt><a name="word3"><b>car-(free)</b>	( car -- )</dt>
<dd>Free the internal data from the heap</dd>
<dt><a name="word4"><b>car-create</b>	( n "&lt;spaces&gt;name" -- ; -- car )</dt>
<dd>Create a cell array in the dictionary with an initial length n</dd>
<dt><a name="word5"><b>car-new</b>	( n -- car )</dt>
<dd>Create a cell array with an initial length n on the heap</dd>
<dt><a name="word6"><b>car-free</b>	( car -- )</dt>
<dd>Free the array from the heap</dd>
</dl>
<h4>Member words</h4>
<dl>
<dt><a name="word7"><b>car-length@</b>	( car -- u )</dt>
<dd>Get the number of elements in the array</dd>
<dt><a name="word8"><b>car-index?</b>	( n car -- flag )</dt>
<dd>Check if the index n is valid in the array</dd>
<dt><a name="word9"><b>car-size!</b>	( +n car -- )</dt>
<dd>Insure the size of the array</dd>
<dt><a name="word10"><b>car-extra@</b>	( car -- u )</dt>
<dd>Get the extra space allocated during resizing of the array</dd>
<dt><a name="word11"><b>car-extra!</b>	( u car -- )</dt>
<dd>Set the extra space allocated during resizing of the array</dd>
<dt><a name="word12"><b>car+extra@</b>	( -- u )</dt>
<dd>Get the initial extra space allocated during resizing of the array</dd>
<dt><a name="word13"><b>car+extra!</b>	( u -- )</dt>
<dd>Set the initial extra space allocated during resizing of the array</dd>
<dt><a name="word14"><b>car-compare@</b>	( car -- xt )</dt>
<dd>Get the compare execution token for sorting the array</dd>
<dt><a name="word15"><b>car-compare!</b>	( xt car -- )</dt>
<dd>Set the compare execution token for sorting the array</dd>
</dl>
<h4>Array words</h4>
<dl>
<dt><a name="word16"><b>car-clear</b>	( car -- )</dt>
<dd>Clear the array</dd>
<dt><a name="word17"><b>car-set</b>	( x n car -- )</dt>
<dd>Set the cell value x at the nth element</dd>
<dt><a name="word18"><b>car-get</b>	( n car -- x )</dt>
<dd>Get the cell value from the nth element</dd>
<dt><a name="word19"><b>car-append</b>	( x car -- )</dt>
<dd>Append the cell value at the end of the array</dd>
<dt><a name="word20"><b>car-prepend</b>	( x car -- )</dt>
<dd>Prepend the cell value at the start of the array</dd>
<dt><a name="word21"><b>car-insert</b>	( x n car -- )</dt>
<dd>Insert the cell value x at the nth element</dd>
<dt><a name="word22"><b>car-delete</b>	( n car -- x )</dt>
<dd>Delete the cell value at the nth position, return the previous cell value x</dd>
</dl>
<h4>Sorting words</h4>
<dl>
<dt><a name="word23"><b>car-sort</b>	( car -- )</dt>
<dd>Sort the array using the compare execution token using heap sort</dd>
<dt><a name="word24"><b>car-find-sorted</b>	( x car -- n flag )</dt>
<dd>Find the cell value x in the already sorted array using binary search, return offset and success</dd>
<dt><a name="word25"><b>car-has-sorted?</b>	( x car -- flag )</dt>
<dd>Check if the cell value x is present in an already sorted array</dd>
<dt><a name="word26"><b>car-insert-sorted</b>	( x car -- )</dt>
<dd>Insert the cell value x sorted in an already sorted array</dd>
</dl>
<h4>Fifo/Lifo words</h4>
<dl>
<dt><a name="word27"><b>car-tos</b>	( car -- x )</dt>
<dd>Get the cell value at the end of the array, exception if array is empty</dd>
<dt><a name="word28"><b>car-push</b>	( x car -- )</dt>
<dd>Push the cell value x at the end of the array</dd>
<dt><a name="word29"><b>car-pop</b>	( car -- x )</dt>
<dd>Pop the cell value from the end of the array, exception if array is empty</dd>
<dt><a name="word30"><b>car-enqueue</b>	( x car -- )</dt>
<dd>Enqueue the cell value x at the start of the array</dd>
<dt><a name="word31"><b>car-dequeue</b>	( car -- x )</dt>
<dd>Dequeue the cell value from the end of the array, exception if array is empty</dd>
</dl>
<h4>Special words</h4>
<dl>
<dt><a name="word32"><b>car-count</b>	( x car -- u )</dt>
<dd>Count the number of occurrences of a cell value x in the array</dd>
<dt><a name="word33"><b>car-find</b>	( x car -- n )</dt>
<dd>Find the offset first occurrence of the cell value x in the array, -1 if not found</dd>
<dt><a name="word34"><b>car-has?</b>	( x car -- flag )</dt>
<dd>Check if a cell value x is present in the array</dd>
<dt><a name="word35"><b>car-execute</b>	( i*x xt car -- j*x )</dt>
<dd>Execute the execution token for every cell in the array</dd>
</dl>
<h4>Inspection</h4>
<dl>
<dt><a name="word36"><b>car-dump</b>	( car -- )</dt>
<dd>Dump the cell array variable</dd>
</dl>
<h3>Examples</h3>
<pre>
include ffl/car.fs


\ Example: simple numeric values in an array


\ Create a dynamic cell array in the dictionary with an initial size of 10

10 car-create values


\ Put values in the array

 7  0 values car-set                             \ Put value 7 on index 0 in values
 1  1 values car-set
 9  2 values car-set
 2  3 values car-set
 4  4 values car-set
 6  5 values car-set
 3  6 values car-set
 5  7 values car-set
 8  8 values car-set
 0 -1 values car-set                             \ Put value 0 on index 9 in values

10  values car-prepend                           \ Prepend value 10 at the start of the array
11  values car-append                            \ Append value 11 at the end of the array

12 5 values car-insert                           \ Insert value 12 on index 5 in the array


\ Get values from the array

.( Value on index 7: ) 7 values car-get . cr     \ Get the value on index 7 (6)

.( Delete second: ) 1 values car-delete . cr     \ Delete the value on index 1 and print this (7)

.( Length: ) values car-length@ . cr             \ Print the length of the array (12)

6 values car-has? [IF]                           \ Check the presence of a value in the array
  .( Value 6 is in the array.) cr
[ELSE]
  .( Value 6 is not in the array.) cr
[THEN]

9 values car-find dup -1 &lt;&gt; [IF]                 \ Find the index of a value in the array
  .( Value 9 is in the array on index: ) . cr
[ELSE]
  drop
  .( Value 9 is not in the array.) cr
[THEN]

values car-sort                                  \ Sort the values in the array

.( Values: ) ' . values car-execute cr           \ Print all values in the array



\ Example 2: store references to date/times in the array

include ffl/dtm.fs


\ Allocate a dynamic array with an initial size of 5 on the heap

5 car-new value dates


\ Create and add five dates to the array

dtm-new 0 dates car-set
dtm-new 1 dates car-set
dtm-new 2 dates car-set
dtm-new 3 dates car-set
dtm-new 4 dates car-set


\ Set the dates

23 dtm.february 2008  0 dates car-get  dtm-set-date   \ saturday
 3 dtm.march    2008  1 dates car-get  dtm-set-date   \ monday
24 dtm.january  2008  2 dates car-get  dtm-set-date   \ thursday
14 dtm.april    2008  3 dates car-get  dtm-set-date   \ monday
 4 dtm.may      2008  4 dates car-get  dtm-set-date   \ sunday

 
\ Sort the dates based on week day

: dates-compare  ( dtm1 dtm2 -- n = Compare two dates for week day )
  dtm-weekday swap dtm-weekday swap &lt;=&gt;
;

' dates-compare dates car-compare!                   \ Set the compare word for sorting

dates car-sort                                       \ Sort the array using the dates-compare word


\ Print the dates

: dates-print  ( dtm -- = Print the date )
  &gt;r ." Day:" r@ dtm-day@ 2 .r ."  Month:" r@ dtm-month@ 2 .r ."  Year:" r&gt; dtm-year@ . cr
;

' dates-print dates car-execute                      \ Print all the dates sorted on week day in the array


\ Free the dates from the heap

' dtm-free dates car-execute


\ Free the array from the heap

dates car-free

</pre>
<hr>
<div align="center">generated 24-Jul-2010 by <b>ofcfrth-0.10.0</b></div>
</body>
</html>
